\chapter{Linux 安装指南}
\label{ch:installation-linux}

本章详细说明如何在 Linux 平台部署 cpp-orchestrator。工具已在 Ubuntu 20.04 及以上、Gentoo、Arch 等主流发行版验证通过。

\section{安装概览}

安装流程包含四类依赖：

\begin{enumerate}
    \item Python 3.11 及以上版本
    \item .NET SDK 8.0+（用于 Roslyn 语义分析）
    \item 支持 C++20 的编译器（g++ 10+/clang++ 13+）
    \item cpp-orchestrator Python 包
\end{enumerate}

\tip{整个安装过程通常耗时 15\textasciitilde 30 分钟，取决于网络与硬件性能。}

\section{环境检查}

在安装前请确认发行版与体系结构：

\begin{lstlisting}[style=bash]
# 查看发行版信息
cat /etc/os-release

# 查看架构
uname -m

# 检查可用空间（至少保留 1 GB）
df -h /
\end{lstlisting}

\section{步骤一：安装 Python 3.11+}
\label{sec:linux-python}

先确认系统中已有 Python 3.11：

\begin{lstlisting}[style=bash]
python3 --version
\end{lstlisting}

若版本满足要求即可跳过，否则根据发行版分别安装：

\begin{itemize}[leftmargin=*]
    \item Ubuntu/Debian 系：启用 deadsnakes PPA 或使用 pyenv
    \item Arch/Gentoo：直接使用官方仓库
    \item 其他发行版：推荐 pyenv 手动构建
\end{itemize}

安装完成后，请将 `python3` 指向 3.11，并安装常用构建依赖（\texttt{build-essential}、\texttt{libssl-dev}、\texttt{libffi-dev} 等）。

\section{步骤二：安装 .NET SDK 8.0+}

Microsoft 提供了官方软件源。以 Ubuntu 为例：

\begin{lstlisting}[style=bash]
wget https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt update
sudo apt install dotnet-sdk-8.0
\end{lstlisting}

安装完成后执行 `dotnet --info` 验证。

\section{步骤三：安装 C++20 编译器}

\begin{itemize}[leftmargin=*]
    \item g++：`sudo apt install g++-12`
    \item clang++：`sudo apt install clang-16`
\end{itemize}

确保编译器默认标准为 C++20，可通过 `c++ --version` 检查。

\section{步骤四：安装 cpp-orchestrator}

建议在隔离的 virtualenv 中安装：

\begin{lstlisting}[style=bash]
python3 -m venv ~/.venvs/cpp-orchestrator
source ~/.venvs/cpp-orchestrator/bin/activate
pip install --upgrade pip
pip install cpp-orchestrator
\end{lstlisting}

安装后可通过 `cpp-orchestrator --help` 验证命令是否可用。

\section{常见问题}

\subsection{Python 版本过低}

若 `python3 --version` 小于 3.11，可使用 pyenv 快速安装：

\begin{lstlisting}[style=bash]
curl https://pyenv.run | bash
export PATH="$HOME/.pyenv/bin:$PATH"
pyenv install 3.11.7
pyenv global 3.11.7
\end{lstlisting}

\subsection{dotnet 命令找不到}

检查安装路径：

\begin{lstlisting}[style=bash]
which dotnet
# 若输出为空，请将 /usr/share/dotnet 加入 PATH
export PATH="$PATH:/usr/share/dotnet"
\end{lstlisting}

\subsection{编译器缺失}

\begin{itemize}[leftmargin=*]
    \item Linux：`sudo apt install build-essential`
    \item Windows 子系统：在 VS 安装程序中勾选“使用 C++ 的桌面开发”
\end{itemize}

\section{安装结果验证}

完成所有步骤后建议运行以下命令：

\begin{lstlisting}[style=bash]
cpp-orchestrator --version
python3 -c "import orchestrator; print(orchestrator.__version__)"
dotnet --info | head -n 5
\end{lstlisting}

若输出版本信息且无错误，即表示 Linux 环境部署成功。
